home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / src / Tools / vtcl / doc / EnterFile.3 < prev    next >
Encoding:
Text File  |  1995-07-10  |  4.5 KB  |  106 lines
  1. '\"
  2. '\" Copyright (c) 1989-1993 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/tcl/man/RCS/EnterFile.3,v 1.4 93/08/27 13:20:42 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. '\"----------------------------------------------------------------------------
  24. '\"    @(#) EnterFile.3 26.1 93/10/22 SCOINC
  25. '\"
  26. '\"     Copyright (C) The Santa Cruz Operation, 1992-1993.
  27. '\"     This Module contains Proprietary Information of
  28. '\"    The Santa Cruz Operation, and should be treated as Confidential.
  29. '\"----------------------------------------------------------------------------
  30. .so ../man.macros
  31. .HS Tcl_EnterFile tclc 7.0
  32. .BS
  33. .SH NAME
  34. Tcl_EnterFile, Tcl_GetOpenFile, Tcl_FilePermissions \- manipulate the table of open files
  35. .SH SYNOPSIS
  36. .nf
  37. \fB#include <tcl.h>\fR
  38. .sp
  39. \fBTcl_EnterFile\fR(\fIinterp, file, permissions\fR)
  40. .sp
  41. int
  42. \fBTcl_GetOpenFile\fR(\fIinterp, string, write, checkUsage, filePtr\fR)
  43. .sp
  44. int
  45. \fBTcl_FilePermissions(\fIfile\fR)
  46. .SH ARGUMENTS
  47. .AS Tcl_Interp checkUsage
  48. .AP Tcl_Interp *interp in
  49. Tcl interpreter from which file is to be accessed.
  50. .AP FILE *file in
  51. Handle for file that is to become accessible in \fIinterp\fR.
  52. .AP int permissions in
  53. OR-ed combination of TCL_FILE_READABLE and TCL_FILE_WRITABLE; 
  54. indicates whether \fIfile\fR was opened for reading or writing or both.
  55. .AP char *string in
  56. String identifying file, such as \fBstdin\fR or \fBfile4\fR.
  57. .AP int write in
  58. Non-zero means the file will be used for writing, zero means it will
  59. be used for reading.
  60. .AP int checkUsage in
  61. If non-zero, then an error will be generated if the file wasn't opened
  62. for the access indicated by \fIwrite\fR.
  63. .AP FILE **filePtr out
  64. Points to word in which to store pointer to FILE structure for
  65. the file given by \fIstring\fR.
  66. .BE
  67.  
  68. .SH DESCRIPTION
  69. .PP
  70. These procedures provide access to Tcl's file naming mechanism.
  71. \fBTcl_EnterFile\fR enters an open file into Tcl's file table so
  72. that it can be accessed using Tcl commands like \fBgets\fR,
  73. \fBputs\fR, \fBseek\fR, and \fBclose\fR.
  74. It returns in \fIinterp->result\fR an identifier such as \fBfile4\fR
  75. that can be used to refer to the file in subsequent Tcl commands.
  76. \fBTcl_EnterFile\fR is typically used to implement new Tcl commands
  77. that open sockets, pipes, or other kinds of files not already supported
  78. by the built-in commands.
  79. .PP
  80. \fBTcl_GetOpenFile\fR takes as argument a file identifier of the form
  81. returned by the \fBopen\fR command or \fBTcl_EnterFile\fR and
  82. returns at \fI*filePtr\fR a pointer to the FILE structure for
  83. the file.
  84. The \fIwrite\fR argument indicates whether the FILE pointer will
  85. be used for reading or writing.
  86. In some cases, such as a file that connects to a pipeline of
  87. subprocesses, different FILE pointers will be returned for reading
  88. and writing.
  89. \fBTcl_GetOpenFile\fR normally returns TCL_OK.
  90. If an error occurs in \fBTcl_GetOpenFile\fR (e.g. \fIstring\fR didn't
  91. make any sense or \fIcheckUsage\fR was set and the file wasn't opened
  92. for the access specified by \fIwrite\fR) then TCL_ERROR is returned
  93. and \fIinterp->result\fR will contain an error message.
  94. If \fIcheckUsage\fR is zero and the file wasn't opened for the
  95. access specified by \fIwrite\fR, then the FILE pointer returned
  96. at \fI*filePtr\fR may not correspond to \fIwrite\fR.
  97. .PP
  98. \fBTcl_FilePermissions\fR returns an OR-ed combination of the
  99. mask bits TCL_FILE_READABLE and TCL_FILE_WRITABLE; these indicate
  100. whether the given file was opened for reading or writing or both.
  101. If \fIfile\fR does not refer to a file in Tcl's file table then
  102. \-1 is returned.
  103.  
  104. .SH KEYWORDS
  105. file table, permissions, pipeline, read, write
  106.